\chapter{\nab}
\label{chap:nabaztag}

\newcommand{\reqbc}{\texttt{GET http://\%s/vl/bc.jsp}}

{\nab} je hračka -- robot ve tvaru králíka (viz obrázek \ref{img:nab:001}). Robot je vybaven {\wifi} kartou, díky níž se
dokáže připojit k počítačové síti a komunikovat se serverem. Interakci s uživatelem zajišťují především reproduktory a
mikrofon. Králík je navíc vybaven pohyblivýma ušima a pěti barevnými světýlky. Na hlavě je umístěno tlačítko.

Samotný robot, bez připojení k síti, neposkytuje žádnou zajímavou funkcionalitu. Až po připojení k ovládacímu serveru
může dojít k načtení bootcodu (operačního systému zařízení). Potom robot tvoří rozhraní mezi uživatelem a ovládacím
serverem, který zpracovává uživatelský vstup a generuje výstup. Může se jednat např. o projev v přirozeném
jazyce nebo o choreografii -- posloupnost příkazů, které řídí mj. polohu uší a barvu jednotlivých světel. Pro komunikaci
mezi roboty a serverem se používají protokoly založené na standardech HTTP a XMPP. Popis používaného v této práci
komunikačního protokolu, jehož základem je norma HTTP, se nachází v kapitole \ref{sec:nab:protocol} na stránce
\pageref{sec:nab:protocol}.

\begin{figure}[!ht]
\centering
\includegraphics[scale=0.4]{images/Nabaztagtag340.jpg}
\caption{Robotický králík Nabaztag:tag. Zdroj fotografie:
\url{http://pl.wikipedia.org/w/index.php?title=Plik:Nabaztagtag\_large.jpg\&filetimestamp=20090129180541}.}
\label{img:nab:001}
\end{figure}

\section{Historie}

Robotického králíka {\nab}, stejně jako jeho předchůdce, Nabaztaga, vyráběla francouzská společnost Violet. Ta také
provozovala jediný oficiální server. Roboti se serverem původně komunikovali pomocí HTTP protokolu, nic\-méně kvůli
velkému zatížení serverů si uživatelé často stěžovali na velmi dlouhou dobu odezvy (dokonce v řádu minut). V březnu 2008
byl HTTP protokol při spojení s roboty nahrazen XMPP protokolem a doba odezvy se výrazně zmenšila, servery byly
nicméně velmi nestabilní a docházelo k dlouhodobým výpadkům poskytovaných služeb.

V roce 2009 ohlásil výrobce robota úpadek a byl převzat společností Mindscape, známá
především jako vydavatel vzdělá\-vacích po\-čí\-tačových her. V červenci 2011 byla podpora dvou prvních verzí robota
Nabaztag (Nabaztag a \nab) pro nerentabilitu ukončena a byl zveřejněn zdrojový kód operačního systému zařízení a serverů
pro obě verze. V~současné době je oficiálně podporována pouze třetí verze robota -- Karotz.

{\nab} připojený k serverům \lstinline!violet.net! umožňoval mj. přehrávání internetového rádia, předpovědí počasí,
čtení e-mailů atp. Konkrétní chování záleželo na tom, které aplikace byly na uživatelském účtu robota aktivovány (pro
přístup k~serveru musel mít králík aktivní účet, identifikován byl pomocí svého sériového čísla). Zprávy, choreografie
atp. se mohly aktivovat na základě pravidelných událostí (např. každou hodinu), vnějších událostí (přijetí e-mailu) nebo
na zák\-ladě událostí generovaných uživatelem (např. nahrání zvuku, který byl serverem rozpoznáván a interpretován).

Roboty bylo možné ovládat pomocí příkazů v přirozeném jazyce. Podpora v první fázi zahrnovala francouzštinu a
angličtinu, v roce 2007 se rozšířila o němčinu, italštinu, španělštinu a holandštinu.
Generování řeči na základě psaných textů (např. čtení zpráv) fungovalo i pro~portugalštinu, dánštinu, finštinu,
islandštinu, švédštinu, norštinu, turečtinu a~pol\-štinu. Zpracování uživatelských příkazů v přirozeném jazyce a
generování zpráv probíhalo pouze na serveru, samotné zařízení umělo pouze nahrát zvuk a poslat ho na server, resp.
vygenerovaný zvuk ze serveru stáhnout.

Velký zájem o internetové králíky a služby s nimi spojené způsobil, že společ\-nost Violet začala vyrábět další
zařízení, která dokázala s Nabaztagy spolupracovat. Mezi ně patřily:
\begin{description}
\item[mir:ror] Čtečka RFID kódů; připojuje se k počítači pomocí USB portu. Reaguje na přítomnost RFID čipů (ztamp:s,
nano:ztag) a spouští na počítači akce přiřazené k jednotlivým čipům (např. otevření internetové stránky).
\item[ztamp:s] Barevné etikety se zabudovanými RFID čipy. Ty je možné přilepovat na různé předměty. Když se
RFID čip dostane do bezprostřední blízkosti králíka \nab  nebo zařízení mir:ror, provede robot akci, která je s ním
spojena.
\item[nano:ztag] Menší barevná verze králíka. Uvnitř je zabudován čip ztamp:s, což umožňuje interakci s většími roboty
{\nab} nebo se čtečkami mir:ror.
\end{description}

\begin{figure}[ht!]
\centering
\includegraphics[scale=0.3]{images/nab-related.jpg}
\caption{Čtečka mir:ror, dva minikrálíci nano:ztag a tři etikety ztamp:s. Zdroj fotografie:
\url{http://fr.wikipedia.org/wiki/Fichier:A-Mirror-2-Nanoztag-and-3-Ztamps.jpg}.}
\end{figure}

Výrobce zpřístupňoval API, které umožňovalo nezávislým poskytovatelům vytvářet a zpřístupňovat služby. Komunikace s
králíky přitom probíhala prostřednictvím webových serverů výrobce.


\section{Technická specifikace robota}

\begin{itemize}
  \item výška: 16 cm bez uší/23 cm s ušima
  \item průměr: 13,5 cm
  \item váha: 1 kg
  \item výměnné pohyblivé magnetické uši
  \item napájení: 110-230 V
  \item Wi-Fi karta: 802.11 b/g
  \item podpora šifrování: WEP a WPA
  \item dva reproduktory 2 W
  \item audiovýstup jack $3.5$ mm pro externí reproduktory nebo sluchátka
  \item ovládání hlasitosti, možnost úplně vypnout reproduktory
  \item mikrofon
  \item čtečka RFID, ISO14443 Type-B
  \item pět barevných diod -- jedna na nose, tři na břichu a jedna na spodní straně
  \item multifunkční tlačítko na hlavě mezi ušima
\end{itemize}

\section{Popis komunikačního protokolu}
\label{sec:nab:protocol}

\nab{} se po spuštění připojí k serveru uvedenému v konfiguraci (viz příloha \ref{chap:app:config} na stránce
\pageref{chap:app:config}) a stáhne svůj operační systém (bootcode). V tomto kroku se vždy použije protokol HTTP. V
dalších krocích robot komunikuje se serverem pomocí protokolu HTTP nebo XMPP -- záleží na konkrétní verzi bootcode. V
této práci používáme starší verzi, která podporuje komunikaci založenou na protokolu \http. Příslušný bootcode (soubor \lstinline!bootcode.bin!) je
součástí knihovny \texttt{volk} (viz kapitola \ref{chap:implementation:volk}) -- tím je splněna jedna z podmínek
nezávislosti naší aplikace na externích poskytovatelích služeb.

Protože zdrojový kód ovládacího serveru a operačního systému králíka byl zveřejněn až poté, co skončila oficiální
podpora výrobce pro roboty Nabaztag a \nab, v červenci 2011, nebyla v době psaní této práce dostupná žádná
oficiální specifikace komunikačního protokolu. Vychá\-zeli jsme tedy z dokumentace k nezávis\-lému serveru
jNabServer\cite{nab001}, která vznikla díky reverse-engineeringu. Protože se nejedná o oficiální dokument výrobce, může
tato specifikace obsahovat malé nepřesnosti. Níže popsaná komunikace je založena na protokolu HTTP 1.0.

\subsection*{Dotazy ({\nab} $\rightarrow$ server)}

Níže uvádíme popis jednotlivých dotazů, které \nab{} odesílá na server. Ve všech příkladech je třeba nahradit řetězec
\texttt{\%s} skutečnou IP adresou serveru v lokální \wifi{} síti. Pořadí jednotlivých volání a odpovědí je znázorněno na
sekvenčním diagramu (obrázek \ref{uml:comm_01} na stránce \pageref{uml:comm_01}).

Téměř vždy se používá metoda \texttt{GET}; výjimkou je dotaz, pomocí kterého \nab{} posílá na server natočený zvukový
záznam, v tom případě tak učiní \texttt{POST}.

\begin{sourcecodedesc}
\item[\reqbc] Tento dotaz králík odešle hned po svém spuštění a nalezení \wifi{} sítě na server uvedený v konfiguraci.
V odpovědi očekává bootcode.
\item[GET http://\%s/vl/locate.jsp] Dotaz je volán po načtení správného
bootcodu. Odpověď by měla obsahovat dvě IP adresy -- jednu pro odesílání běžných dotazů, druhou pro odesílání natočeného
zvuku. V této práci používáme pro oba účely stejný server. V~případě serverů nezávislých na výrobci jsou typicky obě
adresy shodné s adresou uvedenou v konfiguraci králíka. Díky tomuto dotazu lze roboty spravovat přes různé servery bez
změny jejich konfigurace -- je tedy nezbytný pro správu velkého množství robotů se stejným nastavením.

V tomto kroku se naposledy používá adresa nastavená v konfiguraci. Potom již králík komunikuje s adresami, které
získá jako odpověď na tento dotaz.
\item[GET http://\%s/vl/p4.jsp] Ping -- tento dotaz zařízení odesílá v pravidelných intervalech (výchozí interval je 10
vteřin, interval lze za běhu robota změnit). Odpověď by měla obsahovat seznam příkazů, které má robot aktuálně vykonat
(podrobný popis příkazů se nachází na stránce \pageref{chap:nab:protocol:commands}).

Králík pokračuje v odesílání požadavků, i když dojde k výpadku komunikace, způsobenému např. výpadkem
serveru nebo nedostupností \wifi{} sítě. Aby králík znovu načetl bootcode a adresy serverů, se kterými má
komunikovat, je třeba provést restart zařízení -- buď fyzický (odpojit králíka od elektřiny a zase připojit) nebo
softwarový (speciálním příkazem).
\item[POST http://\%s/vl/record.jsp] Tento dotaz zavolá robot po natočení zvukového záznamu. Jeho datová (\texttt{POST})
část obsahuje natočený zvuk zakódovaný ve formátu ADPCM2. Dotaz může být robotem pro každý
zvukový záznam zavolán několikrát.
\item[GET http://\%s/vl/rfid.jsp] Tento dotaz přichází v úvahu, když robot
detekuje přítomnost RFID čipu. Metody pro práci s RFID čipy nebyly v této práci
implementovány.
\end{sourcecodedesc}

\begin{figure}[t]
\centering
\includegraphics{images/seq_communication.eps}
\caption{Schéma komunikace mezi robotem a HTTP serverem.}
\label{uml:comm_01}
\end{figure}

\subsection*{Příkazy (server $\rightarrow$ \nab)}
\label{chap:nab:protocol:commands}

Odpověď na dotaz \texttt{GET http://\%s/vl/p4.jsp} typicky obsahuje balík příkazů pro robota. Ten sestává z pole bajtů,
které vždy začíná znakem \lstinline!0x7f! a končí sekvencí dvou bajtů \lstinline!0xff 0x0a!. Uvnitř
balíku se může nacházet libovolný počet příkazů. Každý příkaz se skládá ze tří částí:

\begin{enumerate}
  \item Typ příkazu (vždy $1$ bajt).
  \item Délka datové části (vždy $3$ bajty). Používá se kódování big-endian.
  \item Datová část (proměnná délka). Nevyskytuje se u všech typů příkazů (tj. délka datové části může být nulová).
  Obsahuje data specifická pro daný typ příkazu.
\end{enumerate}

Níže popisujeme jednotlivé příkazy. V závorkách u názvu uvádíme hodnotu bajtu označujícího typ.

\begin{description}
\item[Nastavení intervalu mezi ping dotazy (0x03)] Pro tento typ příkazu datová část obsahuje vždy 1 bajt, který
určuje, jak často (v sekundách) má robot odesílat na server ping dotazy.
\item[Softwarový restart (0x09)] Po přijetí toho příkazu \nab{} znovu odešle dotaz na bootcode, zeptá se na adresy
serverů atd. Frekvence odesílání ping dotazu se přenastaví na výchozí hodnotu. Pokud balík s tímto příkazem obsahuje
nějaké další příkazy, králík je ignoruje.
\end{description}

\textbf{Skript (0x0A)} je zvláštním typem příkazu. Dostupný skriptovací jazyk je velmi jednoduchý a umožňuje pouze
volat předdefinované procedury. Jednotlivá volání jsou od sebe oddělena pomocí znaku nového řádku (\lstinline!0x0D!). Některé
procedury vyžadují parametr -- ten se od jejich názvu odděluje jednou mezerou: \lstinline!metoda parametr!.

Celý skript je zakódován následujícím způsobem:
\begin{equation}
E[i] = (T[i] - 47) \cdot (1 + 2 \cdot E[i - 1])
\end{equation}
kde $E[i]$ je kód ASCII i-tého znaku zakódovaného textu, $T[i]$ je kód ASCII i-tého znak nekódovaného textu, $E[0]=-1$
(indexování textu od $1$).

Dostupné jsou následující procedury:
\begin{sourcecodedesc}
\item[ID] Identifikátor skriptu. Každý skript musí obsahovat volání této procedury, jinak na něj králík nebude
reagovat.
\item[CL] Rozsvícení světýlka. Procedura vyžaduje parametr v následu\-jí\-cím formátu:
\texttt{0xLLRRGGBBh}, kde \texttt{LL} je číslo diody, a \texttt{RRGGBB} je definice požado\-vané barvy v RGB modelu.
\item[PL] Nastavení palety barev pro choreografie. Parametr -- id palety.
\item[CH] Přehrávání choreografie. Parametr -- URL choreografie.
\item[ST] Přehrávání streamu, např. internetového rádia. Parametr -- URL streamu.
\item[MU, MC] Přehrávání zvukového souboru (oba názvy označují tutéž proceduru). Robot nejprve celý soubor stáhne.
Parametr -- url souboru.
\item[MW] Očekávání na vykonání dříve volaných procedur. Metoda nepřijímá žádné parametry.
\end{sourcecodedesc}

\subsection*{Choreografie}
\label{chap:nab:protocol:choreography}

Choreografie jsou binární soubory, které obsahují posloupnosti příkazů ovládajících pohyby uší, rozsvěcení diod na
králíkovi a přehrávání MIDI zvuků. Každý soubor začíná čtyřbajtovou hlavičkou s informací o délce datové části a končí
čtyřmi nulovými bajty (viz příklad \ref{lst:nab:choreography}).

Datová část se skládá z posloupností bajtů, které reprezentují jednotlivé příkazy.

\begin{description}
\item[1. bajt] určuje délku čekání na provedení příkazu po \textbf{začátku} provádění
předchozího příkazu.
\item[2. bajt] určuje typ příkazu.
\item[3. a následující bajty] jsou parametry příkazu.
\end{description}

Dále prezentujeme seznam podporovaných příkazů. V závorkách uvádíme syntax příkazu -- jeho typ (první bajt) a parametry
(ostatní bajty) v hexadecimálním zápisu.

\begin{description}
\item[Nastavení tempa (\texttt{01TT})] Nastavení rychlosti přehrávání choreografie. Parametr \texttt{TT} určuje novou
rychlost. Výchozí hodnota je \texttt{0x0a}.
\item[Rozsvícení světla (\texttt{07LLRRGGBB0000})] Rozsvícení zvoleného světýlka. Parametr \texttt{LL}
je číslo \texttt{0x00} až \texttt{0x04}, které určuje, které světlo se má rozsvítit. Následují tři bajty, které určují
červenou, zelenou a modrou složku výsledné barvy. Na konci jsou vždy dva nulové bajty.
\item[Nastavení absolutní pozice ucha (\texttt{08EEPPDD})] Parametr \texttt{EE} určuje, kterého ucha se příkaz bude
týkat (\texttt{0x00} -- pravé, \texttt{0x01} -- levé). Pomocí následujícího parametru se nastavuje požadovaná pozice
ucha (číslo v rozsahu \texttt{0x00} až \texttt{0x12}, \texttt{0x00} značí vzpřímenou pozici).
Pomocí posledního parametru lze nastavit směr, ve kterém se má ucho naklopit (\texttt{0x00} -- dopředu, \texttt{0x01} --
dozadu).
\item[Přehrání náhodného MIDI zvuku (\texttt{10})] Přehrání náhodně zvoleného krát\-kého zvuku. Tento příkaz nevyžaduje
žádné parametry.
\item[Změna pozice ucha (\texttt{11EESS})] Tento příkaz přijímá dva parametry -- označení ucha a počet kroků, o
kolik se má ucho otočit dopředu.
\end{description}

\begin{lstlisting}[label=lst:nab:choreography, numbers=left, caption={Příklad choreografie. Dvojice znaků zde odpovídají
bajtům v hexadecimálním zápisu. Pro zlepšení čitelnosti byly přidány bílé znaky a číslování řádků.}]
00 00 00 22
00 01 30
00 10
00 00 ff 00 00 00 00
01 01 00 ff 00 00 00
01 02 00 00 ff 00 00
01 08 00 00 00
01 08 01 00 01
\end{lstlisting}
